Publisher & Subscriber Standards
Contents
Authentication and authorisation
Message delivery mode and rrder
Purpose
This document represents a list of technological and technical standards of the National Event Management Service (NEMS) platform for its publishers, subscribers, and NEMS operators to adhere to in their development and operations.
The NEMS Standards adhere to the Health New Zealand | Te Whatu Ora API Standards:, including the AsyncAPI Standards (work in progress), and service level standards.
Audiences
The NEMS Standards are aimed at those considering, designing, developing, or planning to develop software to produce or consume event notifications; as well as the operators of the platform to manage the development, operation and maintenance of the platform.
NEMS Standards
AsyncAPI
NEMS adheres to the AsyncAPI specification standard. The NEMS API (AsyncAPI) shall be published to the Digital Services Hub.
Authentication and authorisation
Authentication and authorisation to use the NEMS platform is managed by the IdP (Identity Provider) integration within the Health NZ Azure AD (Microsoft Entra ID) team.
This authentication and authorisation is for all client application connections, including publishers and subscribers, as well as access (human & machine) to the platform portal for operational purposes.
The authentication and authorisation follows the OAuth2.0 standard with client credential flow for client applications; and OIDC standard for platform portal access (including the Solace and Solace Datadog instances).
Protocols
NEMS supports the event notification protocols listed below with underlying Solace platform:
- SMF (Solace Message Format)
- AMQP
- MQTT
- REST
- Websocket.
REST is the preferred protocol for publishers; SMF for subscribers.
Connectivity
- Publishers – HTTPS based publisher API endpoint.
- Subscribers – TCPS based JMS style connectivity.
Topic taxonomy
Topic taxonomy represents the event topic hierarchies to deal with large event data sets. The NEMS topic taxonomy has the following structure:
See Topic Taxonomy
Message metadata
NEMS message metadata adheres to the CloudEvents specification Cloud Events Specification.
For the Death Event, the message header specification is as follows: Death Event Message Header.
Message payload
The NEMS message payload should adhere to a ‘thin’ message principle, meaning limited details of the event content are contained in the notification payload. The payload, if any, should be in json format.
The event should consistently contain the minimum information and leverage obfuscation where necessary, especially for those events containing sensitive data. Event consumers should rely on the APIs of the event-producing services for data retrieval and enrichment, rather than the notification payload.
As an example, for Death Event, the message payload includes deathDate and callbackUrl
For more details about death event message payload: Payload.
Message delivery mode and order
NEMS uses “Guaranteed Messaging” delivery mode to ensure successful message delivery between the publisher and subscriber.
The messages are delivered in the order they were published.
FHIR subscription
NEMS will support Fast Healthcare Interoperability Resources (FHIR) subscription as a part of the FHIR standards.
Network
The publisher sends events to the REST-based event publishing endpoint, which is a Solace event broker endpoint with port 9443.
The subscriber connects to the Solace broker SMF TLS/SSL at port 55443. For AMQP, MQTT and other protocols, Solace default ports are used.